The Correct Way to Reference Dynamic Link Libraries (DLLs) in .NET Projects

TLDR

• Prioritize using NuGet for package management to resolve issues with version control, Framework compatibility, and dependency management.
• If you must reference a local DLL, create a dedicated folder (not the bin directory) to store it and include that folder in version control.
• Strictly avoid referencing DLLs directly from the bin directory; this causes compilation failures due to missing sources and prevents unified version management.
• For Website Projects (WSP), ensure the automatically generated .dll.refresh files are included in version control to guarantee the correct reference source.

Why You Should Prioritize NuGet for Package Management

In .NET projects, referencing DLL files directly is not a best practice. It is recommended to use NuGet for management for the following reasons:

• Upgrading and downgrading versions is simple.
• NuGet automatically handles Framework compatibility and downloads the most suitable version based on project settings.
• It automatically resolves dependency issues between packages, downloading required dependencies during installation.
• For internal company libraries, it is recommended to set up a private NuGet Server and manage libraries by packaging them as NuGet packages.

The Correct Way to Reference Local DLLs

When you cannot use NuGet and must reference a local DLL, follow these steps to ensure smooth collaboration:

1. Create a dedicated folder under the solution directory (it is recommended to name it to avoid confusion with packages).
2. Place all DLL files that need to be referenced into this folder.
3. Point all project reference paths to this folder.
4. You must include this folder in your version control system to ensure all team members can obtain the same DLL files.

的正確方式/nuget-packages-folder-reference.png)

Risks of Referencing the bin Directory Directly

When does this problem occur: Developers, for convenience, copy DLLs directly into the compilation output directory bin and reference them from there.

• Compilation Failure Risk: The bin directory is usually not included in version control. If a DLL is placed in bin and referenced, cleaning the project or deleting the bin directory will cause the source path recorded in the project file (.csproj) to become invalid, preventing a successful rebuild.
• Version Management Chaos: If there are multiple projects in the same solution, each referencing DLLs from their respective bin directories, it is easy for different projects to reference different versions of the same DLL, making it difficult to control.

的正確方式/bin-folder-missing-reference.png)

Special Handling for Website Projects (WSP)

When does this problem occur: When using Website Project (WSP) type projects, which lack traditional project files (.csproj) and require a special mechanism to record reference sources.

When adding a reference in a WSP, a {DLL name}.dll.refresh file is generated in the bin directory. This file records the actual source path of the DLL reference.

TIP

Although the bin directory itself is not recommended for version control, the .dll.refresh files within it must be included in version control to ensure that other developers can correctly identify the DLL reference source when restoring the project.

的正確方式/dll-refresh-file.png) 的正確方式/dll-refresh-content.png)

Change Log

• 2022-09-30 Initial document creation.